home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-03 / bv0687.zip / BV0687.TXT < prev   
Text File  |  1992-11-12  |  17KB  |  398 lines
  1. ======================================================================
  2.     Microsoft Product Support Services Application Note (Text File)
  3.                    BV0687: HOW TO USE CALL INTERRUPT
  4. ======================================================================
  5.                                                   Revision Date: 11/92
  6.                                                       No Disk Included
  7.  
  8. The following information applies to Microsoft Basic Languages
  9. versions (see below).
  10.  
  11.  --------------------------------------------------------------------
  12. | INFORMATION PROVIDED IN THIS DOCUMENT AND ANY SOFTWARE THAT MAY    |
  13. | ACCOMPANY THIS DOCUMENT (collectively referred to as an            |
  14. | Application Note) IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY      |
  15. | KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO    |
  16. | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A     |
  17. | PARTICULAR PURPOSE. The user assumes the entire risk as to the     |
  18. | accuracy and the use of this Application Note. This Application    |
  19. | Note may be copied and distributed subject to the following        |
  20. | conditions: 1) All text must be copied without modification and    |
  21. | all pages must be included; 2) If software is included, all files  |
  22. | on the disk(s) must be copied without modification [the MS-DOS(R)  |
  23. | utility DISKCOPY is appropriate for this purpose]; 3) All          |
  24. | components of this Application Note must be distributed together;  |
  25. | and 4) This Application Note may not be distributed for profit.    |
  26. |                                                                    |
  27. | Copyright 1989-1992 Microsoft Corporation. All Rights Reserved.    |
  28. | Microsoft and MS-DOS are registered trademarks and Microsoft       |
  29. | QuickBasic, Visual Basic, and Windows are trademarks of Microsoft  |
  30. | Corporation. OS/2 is a registered trademark licensed to Microsoft  |
  31. | Corporation.                                                       |
  32.  --------------------------------------------------------------------
  33.  
  34.  
  35.                              INTRODUCTION
  36.                              ============
  37.  
  38. The information in this application note applies to:
  39.  
  40.  - The Standard and Professional Editions of Microsoft Visual Basic
  41.    for MS-DOS, version 1.0
  42.  - Microsoft QuickBasic for MS-DOS, versions 4.0, 4.0b, and 4.5
  43.  - Microsoft Basic Compiler for MS-DOS, versions 6.0 and 6.0b
  44.  - Microsoft Basic Professional Development System (PDS) for MS-DOS,
  45.    versions 7.0 and 7.1
  46.  
  47. The information in this application note is also included in the Help
  48. file provided with the Standard and Professional Editions of Microsoft
  49. Visual Basic for MS-DOS, version 1.0.
  50.  
  51. The CALL INTERRUPT and CALL INTERRUPTX statements documented in this
  52. application note are similar to the CALL INT86 and CALL INT86X
  53. statements supported in Microsoft QuickBasic for MS-DOS, versions 2.0,
  54. 2.01, and 3.0. The CALL INT86 and CALL INT86X statements also provide
  55. access to the ROM BIOS and MS-DOS interrupts but use an array
  56. interface instead of user-defined TYPEs. CALL INT86 and CALL INT86X
  57. are documented on pages 148-149 of the "Microsoft QuickBASIC Compiler"
  58. manual for versions 2.0, 2.01, and 3.0. Although there are
  59. differences, some of the information in this application note will be
  60. useful to those who use Microsoft QuickBasic for MS-DOS, versions 2.0,
  61. 2.01, and 3.0.
  62.  
  63. CALL INTERRUPT is a complicated statement that allows programmers to
  64. access low-level MS-DOS and ROM BIOS interrupts and to control these
  65. interrupts from Basic. Effective use of the complex CALL INTERRUPT
  66. interface requires an understanding of the Basic programming
  67. environment, the Basic language, and lower-level MS-DOS and ROM BIOS
  68. functions. This application note explains some of these topics,
  69. including the following:
  70.  
  71. 1. Libraries and Quick libraries
  72.  
  73. 2. User-defined TYPEs
  74.  
  75. 3. INCLUDE files
  76.  
  77. 4. CALL INTERRUPT input and output
  78.  
  79. 5. Differences between CALL INTERRUPT and CALL INTERRUPTX
  80.  
  81. The CALL INTERRUPT statement is designed to call only MS-DOS
  82. interrupts and is not supported in MS OS/2(R) protected mode. Most of
  83. the functions provided by MS-DOS interrupts are available in MS OS/2
  84. protected mode, but are accessed through application programming
  85. interface (API) calls. Most interrupts will work correctly in MS OS/2
  86. real mode (the MS-DOS version 3.x box).
  87.  
  88.  
  89.                      LIBRARIES AND QUICK LIBRARIES
  90.                      =============================
  91.  
  92. The object code for the interrupt routines is located in the
  93. VBDOS.LIB, VBDOS.QLB, QB.LIB, QB.QLB, QBX.LIB, and QBX.QLB files,
  94. which are supplied with Visual Basic for MS-DOS, version 1.0;
  95. Microsoft QuickBasic for MS-DOS, versions 4.0, 4.0b, and 4.5; Basic
  96. Compiler for MS-DOS, versions 6.0 and 6.0b; and Basic Professional
  97. Development System (PDS) for MS-DOS, versions 7.0 and 7.1.
  98.  
  99. The difference between LINK libraries (.LIB files) and Quick libraries
  100. (.QLB files) is that Quick libraries serve as executable code modules
  101. for use within the Visual Basic for MS-DOS or Microsoft QuickBasic
  102. programming environments, whereas LINK libraries are used at link time
  103. to produce executable programs.
  104.  
  105. To load a Quick library for use with the Visual Basic for MS-DOS or
  106. Microsoft QuickBasic programming environments, you must start Visual
  107. Basic for MS-DOS or Microsoft QuickBasic with the /L option (that is,
  108. "VBDOS /L VBDOS.QLB" or "QB /L QB.QLB" or "QBX /L QBX.QLB"). This will
  109. allow you to make CALLs to the routines in that Quick library. When
  110. you choose Make EXE File from the Run menu, your program will
  111. automatically be linked with the library (.LIB file) of the same name
  112. as your Quick library (in this case, VBDOS.LIB, QB.LIB, or QBX.LIB).
  113.  
  114.  
  115.                           USER-DEFINED TYPES
  116.                           ==================
  117.  
  118. To use the CALL INTERRUPT statement, you must first create a user-
  119. defined TYPE to contain the registers for the interrupt. The TYPEs are
  120. defined in the INCLUDE file (VBDOS.BI, QB.BI, or QBX.BI) that comes
  121. with Visual Basic for MS-DOS, version 1.0; with Microsoft QuickBasic
  122. for MS-DOS, versions 4.0, 4.0b, and 4.5; and Basic PDS for MS-DOS,
  123. versions 7.0 and 7.1. For example:
  124.  
  125.    TYPE RegType
  126.         ax    AS INTEGER
  127.         bx    AS INTEGER
  128.         cx    AS INTEGER
  129.         dx    AS INTEGER
  130.         bp    AS INTEGER
  131.         si    AS INTEGER
  132.         di    AS INTEGER
  133.         flags AS INTEGER
  134.    END TYPE
  135.    
  136.    TYPE RegTypeX                     ' See Note below.
  137.         ax    AS INTEGER
  138.         bx    AS INTEGER
  139.         cx    AS INTEGER
  140.         dx    AS INTEGER
  141.         bp    AS INTEGER
  142.         si    AS INTEGER
  143.         di    AS INTEGER
  144.         flags AS INTEGER
  145.         ds    AS INTEGER
  146.         es    AS INTEGER
  147.    END TYPE
  148.    
  149.   NOTE: RegTypeX is used with the CALL INTERRUPTX statement, which
  150.   allows you to specify the DS and ES registers. For more information
  151.   on CALL INTERRUPTX, please refer to the section "Differences Between
  152.   CALL INTERRUPT and CALL INTERRUPTX" later in this application note.
  153.  
  154.                                    
  155.                              INCLUDE FILES
  156.                              =============
  157.  
  158. To simplify the TYPE definition for interrupts, the INCLUDE file
  159. VBDOS.BI, QB.BI, or QBX.BI is shipped with Visual Basic for MS-DOS,
  160. version 1.0; with Microsoft QuickBasic for MS-DOS, versions 4.0, 4.0b,
  161. and 4.5; with Basic Compiler for MS-DOS, versions 6.0 and 6.0b; and
  162. with Basic PDS for MS-DOS, versions 7.0 and 7.1. VBDOS.BI, QB.BI, and
  163. QBX.BI have the TYPE definitions (see a TYPE example later in this
  164. application note) and SUB declarations needed for the interrupt. To
  165. use this file, place the metacommand $INCLUDE at the beginning of your
  166. code.
  167.  
  168. Use the following $INCLUDE statement for Visual Basic for MS-DOS:
  169.  
  170.    REM $INCLUDE: 'VBDOS.BI'
  171.  
  172. Use the following $INCLUDE statement for Microsoft QuickBasic for
  173. MS-DOS:
  174.  
  175.    REM $INCLUDE: 'QB.BI'
  176.  
  177. Use the following $INCLUDE statement for Basic PDS for MS-DOS:
  178.  
  179.    REM $INCLUDE: 'QBX.BI'
  180.  
  181. Please note the following:
  182.  
  183.  - The $INCLUDE metacommand is placed in a REM (comment) statement.
  184.  
  185.  - A colon (:) follows $INCLUDE.
  186.  
  187.  - The filename VBDOS.BI, QB.BI, or QBX.BI is enclosed in single
  188.    quotation marks ('VBDOS.BI' or 'QB.BI' or 'QBX.BI').
  189.  
  190.  
  191.                     CALL INTERRUPT INPUT AND OUTPUT
  192.                     ===============================
  193.  
  194. Besides the interrupt number, there are two other parameters for the
  195. CALL INTERRUPT statement: the input registers and the output
  196. registers. Before you use these registers, you must dimension two
  197. variables as the RegType defined earlier. For example:
  198.  
  199.    DIM inregs as RegType, outregs as RegType
  200.  
  201. For most interrupts, you need to pass some information (function
  202. number, function parameters) in one or more of the registers. This
  203. assignment is performed on individual elements of the user-defined
  204. TYPE inregs. For example:
  205.  
  206.    inregs.AX = &H1A00
  207.  
  208. Note that the above assignment uses hexadecimal values--denoted by the
  209. "&H"--instead of decimal values. Most references for interrupts use
  210. hexadecimal numbers rather than decimal numbers because the high-order
  211. (1A) and low-order (00) bytes are easier to distinguish in hexadecimal
  212. notation.
  213.  
  214. For some interrupts, you must set the high-order or low-order byte of
  215. a register. These bytes are referred to in technical literature with
  216. "H" or "L" replacing "X." For example, the high-order and low-order
  217. bytes of the BX register are BH and BL, respectively. To assign the
  218. registers when given high-order and low-order bytes, concatenate the
  219. hexadecimal values. For example, if you need to assign CH the value
  220. 2Bh and assign CL the value 3Dh, you would assign CX as follows:
  221.  
  222.    ' High-order byte = &H01    Low-order byte = &H00
  223.    inregs.CX = &H2B3D
  224.  
  225. If you are given only 1 byte (high order or low order), the other byte
  226. should be assigned 00 (two zeros). For example, you would set AH to
  227. the value 01h as follows:
  228.  
  229.    ' High-order byte = &H01    Low-order byte = &H00
  230.    inregs.AX = &H0100
  231.  
  232.   NOTE: The above statement is NOT equivalent to "inregs.AX=&H01". You
  233.   must specify the low-order byte, or the value will be stored as
  234.   &H0001.
  235.  
  236. Once you have set the values of the input registers, you are ready to
  237. make the CALL. The syntax of CALL INTERRUPT is as follows:
  238.  
  239.    CALL INTERRUPT(IntNum%, inregs, outregs)
  240.  
  241. If an interrupt returns any values, those values will be passed back
  242. in the outregs variable. As with inregs, values will often be passed
  243. in the high-order or low-order bytes of a register. The routine
  244. BreakWord() in the "Example of CALL INTERRUPT" section below breaks a
  245. register into the 2-byte values.
  246.  
  247. With many interrupts, you need to check only a single bit (or a few
  248. bits) of any register. This is done using the bitwise operators AND,
  249. OR, XOR, and NOT. For example, the following statement will check to
  250. see if the third bit of AX is set:
  251.  
  252.    IF (outregs.AX AND &H4) THEN     ' 4 in hex = 100 in binary
  253.      PRINT "3rd Bit is on"
  254.    END IF
  255.  
  256.  
  257.                        EXAMPLE OF CALL INTERRUPT
  258.                        =========================
  259.  
  260. The following program gives an example of the CALL INTERRUPT statement
  261. and provides two utility SUB programs for processing output:
  262.    
  263.    '__________________________ INTSKEL.BAS _________________________
  264.    '
  265.    '     Skeleton program for calling MS-DOS or ROM BIOS interrupts
  266.    '     from Visual Basic, Microsoft QuickBasic, or Basic PDS.
  267.    '
  268.    '     To try this example in VBDOS.EXE:
  269.    '      1. From the File menu, choose New Project.
  270.    '      2. Copy the code example to the Code window.
  271.    '      3. Press F5 to run the program.
  272.    '
  273.    '     NOTE: The VBDOS and Microsoft QuickBasic environments must be
  274.    '           started with the /L option to load the default Quick
  275.    '           library. The VBDOS.QLB, QB.QLB, or QBX.QLB Quick
  276.    '           libraries provide support for CALL INTERRUPT and
  277.    '           CALL INTERRUPTX.
  278.    '
  279.    '     There are also two SUB programs, BreakWord() and IntToBin(),
  280.    '     that you may find useful when CALLing interrupts.
  281.    '_________________________________________________________________
  282.    
  283.    DEFINT A-Z
  284.    CONST TRUE = -1
  285.    CONST FALSE = NOT TRUE      ' FALSE is assigned to 0 here.
  286.    
  287.    ' Use the following INCLUDE file for Visual Basic for MS-DOS:
  288.    '$INCLUDE: 'VBDOS.BI'        ' Take a look at what is in this file.
  289.    ' Use the following INCLUDE file for Microsoft QuickBasic for
  290.    ' MS-DOS.
  291.    '$INCLUDE: 'QB.BI'           ' Take a look at what is in this file.
  292.    ' Use the following INCLUDE file for Basic PDS for MS-DOS:
  293.    '$INCLUDE: 'QBX.BI'          ' Take a look at what is in this file.
  294.    
  295.    DIM inregs AS RegType, outregs AS RegType
  296.    
  297.    '------------------------------------------------------------------
  298.    ' Load registers with the required input parameters for the call
  299.    ' that you want to make. (See any reference for MS-DOS and/or ROM
  300.    ' BIOS calls.)
  301.    '
  302.    ' Example: For Interrupt 10h, with function 0Ah (ROM BIOS Write
  303.    ' Char)
  304.    '          AH = 0Ah. Note: The function number usually goes in AH.
  305.    '          AL = Character code (ASCII)
  306.    '          BH = Video page number = 0 normally
  307.    '          BL = Color in graphics mode
  308.    '          CX = Number of these characters to write to screen
  309.    '------------------------------------------------------------------
  310.    CLS
  311.    ' ASCII character 251 decimal, square root symbol.
  312.    character% = &HFB
  313.    functnum% = &HA00   ' Remember you want the function in the
  314.                        ' HIGH-ORDER byte of AX.
  315.    
  316.    ' VERY IMPORTANT! Don't put the function number in the wrong
  317.    ' byte of AX, or the program may hang or give unpredictable
  318.    ' results!
  319.    
  320.    inregs.ax = character% OR &HA00
  321.    inregs.cx = 2000      ' Fill the screen.
  322.    CALL interrupt(&H10, inregs, outregs)
  323.    
  324.    DEFINT A-Z
  325.    '__________________________________________________________________
  326.    '
  327.    '     BreakWord() takes an integer argument and returns two
  328.    '     integers representing the high-order and low-order bytes of
  329.    '     the original number in base 10 decimal notation.
  330.    '__________________________________________________________________
  331.    '
  332.    SUB BreakWord (dataword, highbyte, lowbyte)
  333.       IF dataword < 0 THEN
  334.         ' Check for high-order BIT set.
  335.         highbyte = (dataword + 2 ^ 16) \ 256
  336.       ELSE
  337.         ' Integer division to remove low-order byte.
  338.         highbyte = dataword \ 256
  339.       END IF
  340.       ' AND operator to remove the top byte.
  341.       lowbyte = dataword AND 255
  342.    END SUB
  343.    
  344.    DEFINT A-Z
  345.    '__________________________________________________________________
  346.    '
  347.    '    The IntToBin() SUB program below takes an INTEGER argument
  348.    '    and produces a binary string representation of the INTEGER.
  349.    '__________________________________________________________________
  350.    '
  351.    SUB IntToBin (byte%, bin$)
  352.    bin$ = ""
  353.    temp% = byte%
  354.    FOR i = 0 TO 7     ' Loop through bits 0 through 7 (8 total).
  355.       IF temp% AND 1 THEN
  356.          bin$ = "1" + bin$
  357.       ELSE
  358.          bin$ = "0" + bin$
  359.       END IF
  360.       ' Division by 2 shifts right 1 binary digit (bit).
  361.       temp% = temp% \ 2
  362.    NEXT
  363.    END SUB
  364.    
  365.    
  366.         DIFFERENCES BETWEEN CALL INTERRUPT AND CALL INTERRUPTX
  367.         ======================================================
  368.  
  369. The CALL INTERRUPT and CALL INTERRUPTX statements are very similar.
  370. Either statement allows you to make calls to MS-DOS and ROM BIOS
  371. interrupts.
  372.  
  373. The only difference is that with INTERRUPTX you can specify the DS and
  374. ES registers. (The documentation for interrupts--see the following
  375. reference section--will state whether those registers are necessary.
  376. For most interrupts, DS and ES are not needed.)
  377.  
  378.  
  379.               REFERENCES FOR DOCUMENTATION ON INTERRUPTS
  380.               ==========================================
  381.  
  382. The following books are excellent resources for the different
  383. interrupts available from MS-DOS and the ROM BIOS. Be aware that the
  384. code in these books is written in assembly language; however, the
  385. necessary input and output is given by register.
  386.  
  387. 1. "Advanced MS-DOS Programming, Second Edition" by Ray Duncan,
  388.    published by Microsoft Press (1988)
  389.  
  390. 2. "The New Peter Norton Programmer's Guide to the IBM PC & PS/2" by
  391.    Peter Norton, published by Microsoft Press (1988) (second edition)
  392.  
  393. 3. "The Programmer's PC Sourcebook (Second Edition)" by Thom Hogan,
  394.    published by Microsoft Press (1991)
  395.  
  396.  
  397.  
  398.